Libris Britannia 4

home *** CD-ROM | disk | FTP | other *** search

/ Libris Britannia 4 / science library(b).zip / science library(b) / PROGRAMM / COBOL / H309.ZIP / PSICO.ZIP / PSICO12.EXE / PSICO.DOC < prev next >

Wrap

Text File | 1993-02-12 | 34KB | 1,057 lines

---------------------------------------------------------------------------- PSICO USER GUIDE VERSION 1.2 ---------------------------------------------------------------------------- CONTENTS Chapter 1. Introduction Chapter 2. Functions Chapter 3. Menu commands Chapter 4. Automatic demonstration mode Chapter 5. Parameters and notes Chapter 6. COBOL techniques and style Chapter 7. Structured COBOL Chapter 8. Online Help Chapter 9. Future versions Appendix A. Reformatting Table definition Appendix B. Structure syntax Appendix C. Example of structured COBOL program ---------------------------------------------------------------------------- CHAPTER ONE ---------------------------------------------------------------------------- INTRODUCTION This program is a utility which is intended to assist in creating structured COBOL source code. It presents to the user a series of templates, which are then used to generate files containing working storage and procedure code. The code generated by the structure commands is restricted to a subset of the full ANS85 COBOL, but should cover most requirements. The facilities provided are believed to be compatible with many different COBOL compilers, from PC to mainframe. However, it may in some circumstances be necessary to edit the generated program to remove incompatibilities. At the end of the run, the files created are merged to create a complete source file. This source can be in one of two formats chosen by a command-line parameter: MODE=C generates ANS85 COBOL source with file extension .CBL MODE=S generates source code in our own structured format, with file extension .STR A source file generated in our own format must then be preprocessed by our COBFORM utility to expand the special structure verbs into ANS74 COBOL. Note that ANY dialect of COBOL may be used, from the UTAH subset up to full ANS85 COBOL such as Micro Focus COBOL/2. In accordance with good practice, the program design should have been completed in a structured format before using PSICO to enter the source code. Extra facilities for registered users ------------------------------------- None as yet. The full mainframe version contains a built-in editor, but I have had stack overflow problems when trying to convert it to the PC. ---------------------------------------------------------------------------- CHAPTER TWO ----------------------------------------------------------------------------- FUNCTIONS --------- Initial process --------------- The program requires a program name as a command-line parameter. This is up to 8 characters long, and will be used for the PROGRAM-ID as well as the names of all output files. Note that all files must be held in the current directory. The program creates skeleton IDENTIFICATION, ENVIRONMENT and DATA divisions. These can be edited later if necessary. Procedure processing -------------------- The program processes one procedure at a time. A procedure is one COBOL SECTION. The Procedure screen accepts the details for the first procedure. The default name can be replaced, and any other details specified (see Chapter 5 and Appendix B for description of the various parameters). We recommend that you set CAPS LOCK on, because all keywords used in the program must be in UPPER case. This is, of course, for compatibility with COBOL. At this point, I should warn you that the program has been converted from an ICL VME program, and the screen processing is based on an emulation of the ICL mainframe terminals. Only the text in unprotected areas from the start of the screen up to the cursor position is accepted, and any data to the right of or below the cursor position is ignored. The unprotected areas are delimited by left and right pointing arrows. A fuller description of the keyboard usage is given in appendix D. When finished, press ENTER. A Comment box will then be displayed for you to complete. Any text typed will be included as COBOL comments in the generated program. To end the program, type N (Upper case only) in the More? field on the procedure screen. You can only exit from the program at a PROCEDURE screen. Although you can quit at any time using the ESCape key, this abandons the processing, and does not create the output program. Structure processing -------------------- The program will display a SEQUENCE structure screen as the first screen within a procedure. You may type any COBOL code within the main ('action') body of the screen, with the leftmost column corresponding to COBOL area B. Special features: If you type an asterisk (*) in the first column, the line will be taken as a COBOL comment line. If you type @ in the first column, the line will be taken as a data item, and written to the WORKING-STORAGE SECTION. This is a very useful facility, allowing you to define data items while entering procedure code. For the time being, ignore the field at the top marked 'Menu'. This is used for other commands described below. When the page is filled, press Enter, and the next screen will be displayed. When you have entered all the code for the sequence, type N in the field named 'More'. So far, this may not seem to be very useful. But you can also enter structure commands, which trigger different types of screen. The structures available are: SEQ the default (sequence) structure WHILE ) loop structures UNTIL ) SELECT Multi-choice condition structure POSIT Special JSP structure (not available if mode = C) ZIF generates an IF-THEN-ELSE structure ZREAD generates a READ .... AT END .... structure BOX generates a comment box A structure command must be coded on a separate line, and anything else on that line will be ignored. It may be used within the action body of any structure, with certain exceptions described below. If, within a SEQUENCE, you type WHILE on the first body line, and UNTIL on the second, then you will be presented with a WHILE screen, and then when completed, an UNTIL screen. The screens are presented in a top-down sequence, ie within the UNTIL, you can code another structure, perhaps a SELECT, which will be completed before the UNTIL is ended. As each structure is completed, the source code is copied out of the stack into the output file. ZIF, WHILE and UNTIL structures ------------------------------- As well as the Menu field and action body lines, a condition line is present. A COBOL condition should be entered here. If there is not enough space, enter a >, and press Enter. An extended condition screen will be provided. There are only 10 lines in the body of the WHILE. If this is not enough, enter SEQ to create a sequence structure. Any number of lines may be included in a sequence. If MODE=C, a PERFORM UNTIL statement is generated, with the condition reversed if the structure is a WHILE loop. ZIF structure ------------- This is an IF-THEN-ELSE structure. If generating ANS85 COBOL, ie MODE=C, then further structures can be nested inside it. This is not possible if MODE=S, (except for a SEQUENCE structure) and you should use the SELECT structure instead. ZREAD structure --------------- This is READ-AT-END structure. If generating ANS85 COBOL, ie MODE=C, then further structures can be nested inside it. This is not possible if MODE=S, and you should use a flag field, and follow the READ by a SELECT structure instead if that facility is required. SELECT structure ---------------- A CASE screen is displayed, which contains a condition and an action body. At the top, a field is present marked 'More cases?'. This should be set to N when all cases have been entered, otherwise a further CASE screen will be displayed. Up to 9,999 cases are allowed in a single SELECT structure. As well as the Menu field and action body lines, a condition line is present. A COBOL condition should be entered here. If there is not enough space, enter a >, and press Enter. An extended condition screen will be provided. The condition may be left blank on the last CASE screen, to act as an ELSE condition. This will automatically terminate the SELECT structure. If MODE=C, a COBOL EVALUATE statement will be generated, with a WHEN clause for each specified CASE. Textual substitution -------------------- Available only if MODE=S This is performed by the preprocessor COBFORM, which uses a table, held in an ASCII text file, to specify any substitutions required. See the COBFORM User Guide for details. ---------------------------------------------------------------------------- CHAPTER THREE ---------------------------------------------------------------------------- Menu commands The Menu command field, which appears on most structure screens, is used to implement various out-of-line processes, such as defining a COBOL file. The following commands are currently available, although more are planned: ? Display menu of commands F Define a file This provides a single screen on which you can enter the SELECT statement, the FD and a data record. These are then written to the appropriate COBOL sections. L Define a linkage data item W Define a working storage data item W and L allow easy entry of individual data items - Up one level in the stack + Down one level The current nest of structures is held in a stack, with the top of stack being the outermost level, which is always a SEQUENCE. These commands allow you to backtrack and change what has been entered. Since the code is written to files at the end of each screen, you can only change lines which have not yet been processed. The current structure is indicated, and you can only change lines BELOW it on the screen. ---------------------------------------------------------------------------- CHAPTER FOUR ---------------------------------------------------------------------------- Automatic demonstration mode ---------------------------- The program contains facilities to record and play back a sequence of keystrokes, in order to create demonstration disks. The following keys are used to control these facilities: F7 Starts recording. This is ALWAYS into a file called PLAY.ASK in the current directory F8 Stops recording F4 Inserts a pause, waiting for a key to be pressed F6 Press this to start playback of file PLAY.ASK After recording, it is advisable to rename PLAY.ASK, to some other name because it will otherwise be overwritten next time you record a session. During the playback F (Faster) Speeds up the playback, as far as possible. The playback always starts at maximum speed S (Slower) Slows down the playback Esc The ESC key returns to DOS at any time during the playback PSICO can use a command line parameter to specify a different script file. I have used extension ASK for scripts, but this is not mandatory. A script file MATCH3.ASK is included in the released software, which will produce either a COBOL85 or a COBFORM demonstration source file depending on the MODE parameter used. Type PSICO MATCH3 MODE=C PLAY=MATCH3.ASK for COBOL85 Type PSICO MATCH3 MODE=S PLAY=MATCH3.ASK for COBFORM Then you can compare the output files MATCHN.CBL, MATCHN.STR. MATCH3.STR, when processed by COBFORM, is compatible with the shareware COBOL600 compiler. MATCH3.CBL is compatible with MicroFocus COBOL/2 ---------------------------------------------------------------------------- CHAPTER FIVE ---------------------------------------------------------------------------- Parameters ---------- The keywords do not need to be given if the parameters are given in the correct order as follows: KEYWORD MEANING ======= ======= PROG= You must enter the program-id. There is no default. MODE= C for ANS85 COBOL, S for COBFORM source. Default is S PLAY= Use this to play back a prerecorded script. You can either specify the script file name, or PLAY=Y to use the default file PLAY.ASK. Default is space (ie no playback). If the script file does not exist, the parameter is ignored. ALL PARAMETERS MUST BE IN UPPER CASE!!!! Best to set the caps lock on first. EXAMPLES: PSICO MATCH3 C PSICO MATCH3 PLAY=Y MODE=S PSICO MATCH3 PLAY=MATCH.ASK ---------------------------------------------------------------------------- CHAPTER SIX ---------------------------------------------------------------------------- COBOL techniques and style: Some ideas on programming in COBOL85 Maintainability =============== In most commercial use, more time is spent maintaining a program over its lifetime than is taken to write it. Therefore ease of maintenance should be a prime concern. This was one of the main reasons for the adoption of Structured Programming techniques. Data definitions ================ In the old days of COBOL, lots of complex data structures, with multiple redefinitions, were the norm, particularly in print programs. Since the introduction of the STRING and UNSTRING commands, much of this has been unnecessary. However, old habits die hard, and this style of code is still to be seen in many places, including textbooks. Nowadays, I NEVER define a print line in working storage, but use the STRING statement, with a pointer, to put data anywhere in a print line which is defined simply as PIC X(132). My programs are now much FASTER to write, EASIER to debug, more RESILIANT to changes in print layout, and QUICKER to modify. Numeric data items are moved to standard edited fields, which are held in a Copylibrary. I use such names as WS-5V2 to mean PIC ZZ,ZZ9V.99, for this purpose. It is even possible to compute the column numbers in the program, and allow for different widths of paper. It is possible to do such useful tasks as calculating the length of the data, and using it to centre headings - easy in BASIC, but not in COBOL. EXAMPLES: ========= MOVE SPACES TO PRINT-LINE MOVE 1 TO WS-COLUMN STRING "TRANTOR LTD" DELIMITED SIZE INTO PRINT-LINE WITH POINTER WS-COLUMN MOVE 60 TO WS-COLUMN STRING "EXAMPLE REPORT" DELIMITED SIZE INTO PRINT-LINE WITH POINTER WS-COLUMN MOVE 110 TO WS-COLUMN MOVE WS-PAGE TO WS-4V0 STRING "PAGE " WS-4V0 DELIMITED SIZE INTO PRINT-LINE WITH POINTER WS-COLUMN This may seem like more typing, but with any decent editor, you can duplicate standard blocks of text, and just replace the changed bits. Just think of the time saved in working out the print line definitions! Using this method, I normally code straight from the print layout. Each item is individually placed on the line, and can be realigned without affecting any other item. Multiple Definitions ==================== One of the main problems when altering a data definition, such as a record format, is in tracing all the places in which the record data items are defined. As well as the definitions in the input, and possibly output, files, there are usually working-storage definitions of all or part of the data. It is often much better to define the input and output records as just simple buffers, and make ONE definition in working storage. Even this is not absolutely necessary, and I have written generalised programs, such as a 'structured record' edit and print, in which the data records are totally defined by tables read from a file. In fact, I have also written a program which reads COBOL data definitions to create these tables in the first place. (A demo version of the editor is available for the PC) The fundamental principle is that a data item should be defined in ONE PLACE ONLY, as far as is possible. The advantages of this approach are that when, for example, a single data item is changed in size, other code is not necessarily affected. (To be continued at the next release) ---------------------------------------------------------------------------- CHAPTER SEVEN ---------------------------------------------------------------------------- Using Structured COBOL (MODE=S only) ------------------------------------ Structure verbs are provided as an extension of the COBOL language. The syntax is defined in appendix B, as well as some suggestions for tailoring the language. The normal use of COBOL is not restricted in any way, and structured procedures may be freely mixed with COBOL sections in the same program. Procedures ---------- A structured program is divided into procedures. Each procedure is equivalent to, and will be expanded into, a COBOL SECTION. A procedure is invoked by PERFORMing the procedure, using a normal COBOL PERFORM statement. Three kinds of procedure are provided: Normal ------ This acts as a normal COBOL routine. Recursive --------- A special verb is provided for the routine to be able to call itself. Return address processing is automatically provided but the user must define appropriate working storage for a stack of return addresses and a stack pointer. See the supplied example for details. Multi-state ----------- Multi-state routines, as used in data-driven structured methodologies, are routines which perform only part of their task on any invocation. When the routine has finished the current part of the task, it saves a note of the current position within the processing in a "state variable", and returns to the calling module. On subsequent reentry, it resumes at the point immediately following the previous exit. A multi-threading variant is also supported, in which the single state variable is replaced by an array, and a "thread" variable is also used, which is a subscript to the array. This type of routine is best left to those familiar with the theory of its use. Number of routines ------------------ Up to 36 procedures may be specified within one program. It should be noted that the top-level routine within a program MUST be a normal procedure, not recursive or multistate. If necessary, a dummy first procedure could be provided which just PERFORMs the required routine. Structures ---------- A number of different types of structure are provided : Sequence -------- Within the structure body, statements are executed in the order in which they are written. Selection --------- The SELECT structure provides any number of conditions, and a structure body associated with each. Only one body will be actioned, which will be the first encountered for which the specified condition is true. An ELSE body may also be specified, which will be executed when none of the specified conditions is true. Iteration (repetition) --------- The body of the structure is executed repeatedly until the termination condition is met. Two kinds of iteration are provided : Iterate until the condition is true Iterate while the condition is true. Structures may be nested to a depth of 36, and any type of structure may be nested within any other. Full specifications of the structure syntax are in Appendix B, and an example of a structured program using all the facilities described is given in Appendix C. Using Recursion --------------- This is a very powerful technique for certain types of program. As the COBOL language does not support recursive calls, the method has not been widely used in the commercial DP world, although in languages such as LISP and PROLOG it is the basic method of processing. A simple routine which uses structured COBOL to build and display a binary tree is given in Appendix C. Error messages -------------- Error and warning messages are inserted as comments into the output text, at the place where the error is discovered. ---------------------------------------------------------------------------- CHAPTER EIGHT ---------------------------------------------------------------------------- Online Help Online help may be obtained from any screen which has a MENU field. To obtain help on any item, type ? followed by that item, eg ?INSPECT, in the MENU field and press ENTER Two help files are provided: PSHELP.C74 with ANS74 COBOL syntax for mode S PSHELP.C85 with ANS85 COBOL syntax for mode C The program will automatically select the correct file depending on the MODE parameter. The files do not pretend to give a full and rigorous definition of COBOL syntax, but are intended to give general assistance. They are simple ASCII text files, and may be edited by the user to add any extra information required. The conventions used include [ ] to bracket optional items { } to enclose multiple choices ╠ ╣ to indicate items or clauses which may be repeated. The search key is an @ in the first column followed by the search subject without intervening space. By default, 21 lines will be shown per page, but a # in column 1 will force a new page. ---------------------------------------------------------------------------- CHAPTER NINE ---------------------------------------------------------------------------- Future versions There is obviously a lot of development potential in this program, but new versions can only be produced if there is user support. Otherwise, I shall have to concentrate on other products. I have plans to introduce on-screen help with COBOL syntax and statement formats, so that if you are unsure of any of the variants of, for example, the UNSTRING statement, you can display a template. Extra validation could be introduced. At present, it is possible to generate an IF structure without a condition, or a READ without the filename. This could be prevented by extra checking. I could also develop a PC-specific version, written in C and using the full PC screen display facilities. Even, perhaps, a Windows version. The current program is itself written in structured COBOL, which produces a larger than necessary EXE file, partly because COBOL does not have dynamic allocation of working storage. Please support me with your registrations if you would like to see these or any other improvements which you can suggest. ---------------------------------------------------------------------------- APPENDIX A ---------------------------------------------------------------------------- Reformatting table definition ----------------------------- See COBFORM Manual ---------------------------------------------------------------------------- APPENDIX B. ---------------------------------------------------------------------------- Structure syntax (MODE=S only) ------------------------------- PROC command ------------ SYNTAX: PROC procname PROCBEGIN procedure-body PROCEND Notes: a) Structure commands may be in COBOL margin A or B b) procname must be valid for a COBOL section name c) procedure-body is an interation and/or a nest of structures This command generates a COBOL section containing the specified structures. EXAMPLE: PROC A-MAIN PROCBEGIN OPEN INPUT INFILE PERFORM B-PROCESS CLOSE INFILE STOP RUN PROCEND IPROC command ------------- SYNTAX: a) Inverted routine IPROC procname PSVNAME numeric-item PROCBEGIN procedure-body PROCEND b) Multithread routine IPROC procname PSVNAME numeric-array PSVTHREAD numeric-item PROCBEGIN procedure-body PROCEND Notes: a) Structure commands may be in COBOL margin A or B b) procname must be valid for a COBOL section name c) procedure-body is an interation and/or a nest of structures d) numeric-item is used as a state variable or as an array index e) numeric-array is an array of state variables This command generates a multi-state routine, which may be either single-thread or multi-thread depending on whether a PSVTHREAD is specified. The multi-state technique is illustrated in the example BINTREE.STR where it is used for creating a binary tree. RPROC command - Recursive procedure ----------------------------------- SYNTAX: RPROC procname PSVNAME numeric-array PSVTHREAD numeric-item PROCBEGIN procedure-body PROCEND Notes: a) Structure commands may be in COBOL margin A or B b) procname must be valid for a COBOL section name c) procedure-body is an interation and/or a nest of structures d) numeric-item is used as a stack pointer e) numeric-array is an array of state variables, used as a stack This generates a recursive routine. Examples are given in BINTREE.STR and FACTORL.STR The subcommand RCALL may be used only within a recursive procedure, and performs the recursion. SEQUENCE structure ------------------ This contains a structure body which is always obeyed once. The body may contain any mix of COBOL statements and structures. EXAMPLE: SEQUENCE MOVE 1 TO WS-COUNT ITERUNTIL WS-COUNT = 10 BEGIN PERFORM DA-PROCESS ADD 1 TO WS-COUNT REPEAT DISPLAY "FINISHED" FI For further examples, see BINTREE.STR supplied with the software. SELECT structure ---------------- This selects one of a number of alternatives for execution. Up to 9999 different cases may be specified. It is also possible to supply a code body which is executed of none of the selection conditions are true, by giving a null condition. EXAMPLE SELECT CASE X = 1 BEGIN PERFORM EA-TYPE-1 CASE X = 2 BEGIN PERFORM EA-TYPE-2 CASE A = "STOP" OR "HALT" BEGIN PERFORM EA-STOP CASE BEGIN PERFORM FA-ERROR FI Notes: a) Only one of the alternatives is obeyed b) The condition can be any valid COBOL condition, including the use of AND and OR. c) The condition MUST be terminated by the word BEGIN. Omitting this is the most common cause of error. d) You can use CASE BEGIN, ie a null condition, instead of OTHERWISE. POSIT structure ---------------- This structure is included to facilitate backtracking and error handling. It allows control to be transferred from any point within the POSIT body (or within any enclosed structure) to the associated ADMIT body. It is in fact a controlled GO TO function, which can avoid deep nesting of IF statements in many cases. EXAMPLE: POSIT MOVE 1 TO I ITERUNTIL I MAX BEGIN IF ITEM(I) = "AA10" QUIT IF ITEM(I) = "CD30" QUIT ADD 1 TO I REPEAT MOVE 0 TO FOUND ADMIT MOVE 1 TO FOUND FI Notes: a) There is no need to put a full stop after the word QUIT. One will be inserted. b) The ADMIT will ONLY be obeyed if a QUIT is executed. c) Any number of QUITs may be coded within the POSIT body or within any enclosed structure. ITERWHILE and ITERUNTIL structures ---------------------------------- These allow repeated execution of selected code. The condition is always evaluated at the START of the loop, allowing for the loop executed zero times ie not at all, if the condition should so indicate. The body may contain any mix of COBOL statements and structures. EXAMPLE: MOVE 0 TO WS-EOF WS-COUNT READ INFILE AT END MOVE 1 TO WS-EOF. ITERUNTIL WS-EOF = 1 ( or ITERWHILE WS-EOF = 0) BEGIN PERFORM DA-PROCESS ADD 1 TO WS-COUNT READ INFILE AT END MOVE 1 TO WS-EOF. REPEAT DISPLAY WS-COUNT " records processed" In this example, a "read-ahead" is performed before entering the main loop. This ensures that the routine works even if there are no records on the input file, and that it correctly counts the number of records read. The use of "read-ahead" is strongly recommended, even when not strictly necessary, as it can often simplify code, and prevents the occurrence of some types of common logic error. For further examples of the SELECT structure, see BINTREE.STR supplied with the software. Notes: a) A full stop is necessary after any conditional clause, eg AT END, ON OVERFLOW, etc. b) The condition may be any valid COBOL condition, and MUST be terminated by the word BEGIN Minor commands -------------- Pseudo-read and write --------------------- SREAD and SWRITE are synonymous, and perform pseudo-read (or pseudo-write) operations. They are valid only within an IPROC. The action is to save a note of the current address in a state variable and exit from the routine. When the routine is reentered, processing resumes at the next instruction rather than at the start. See PROC BA-BUILD-TREE in BINTREE.STR for a good example RCALL - Recursive call ---------------------- RCALL performs a recursive call, and is valid only in an RPROC. It saves the current address in a stack of state variables, increments the stack pointer, and starts again at the beginning of the procedure. At the end of the procedure, the stack is unwound, and processing resumes at the previous level of the stack. Examples are to be found in both FACTORL.STR and BINTREE.STR Tailoring the language ---------------------- The structure commands are not actioned until after the textual replacement so you can replace any structure command by a word of your own choice. For example, you could use WHEN instead of CASE, DO instead of BEGIN, and WEND instead of FI. If you prefer abbreviations, how about ? for SELECT, [ for ITERWHILE, ] for repeat, and ! for BEGIN. The only thing to watch is for possible conflicts with COBOL. For example, it is not a good idea to use UNTIL, because this would preclude the use of PERFORM ... UNTIL . ---------------------------------------------------------------------------- APPENDIX C. ---------------------------------------------------------------------------- Example of structured program ----------------------------- Please see programs BINTREE.STR and FACTORL.STR on the disk. There didn't seem to be much point in including them here as well! ---------------------------------------------------------------------------- APPENDIX D. ---------------------------------------------------------------------------- Keyboard facilities. -------------------- This program uses our ASK_MESSAGE emulator subroutine for formatted screen handling. The key functions follow, as far as practicable, the ICL terminals used for VME MAC. Data can only be entered in unprotected fields, delimited by right pointing triangle (start of unprotected) and left-pointing triangle. The following keys have special functions: ESC Immediately terminates the program with the display "ESCAPED". The screen is NOT cleared. Home Moves the cursor to the SOM (Start of Message marker) This is usually the first unprotected field on the screen TAB Tab to next unprotected field Shift + TAB Tab to previous unprotected field (BackTab) These cycle from end to start of screen if necessary PGUP, PGDN Not used F1 Insert line (emulates CTRL+INS) F2 Delete line (emulates CTRL+DEL) F5 May be used to enter almost any non-keyboard character. It should be followed by the 3-digit ASCII number for the character. The number must be in the range 032 to 255, as 0 to 32 are reserved for program use. See also F10 F4 ) F6 ) Special record and play facilities - see Chapter 3 F7 ) F8 ) F9 Configuration menu. At this release, it only allows colours to be changed. The new colours can be saved into a configuration file. F10 Character selection. A menu is displayed which allows easy selection of most non-keyboard characters. Note that only the text from the SOM (Start of Message) to the cursor is used by the program. This is for compatibility with the Mainframe version of the program. On a Colour screen, the SOM is marked with a red background. If the cursor is sent to the SOM by using the Home key, then the whole screen is sent.